v1.17.0

Compare Source

Two new CLI surfaces (git-diff-driver, --open), header-default flip, walker foundation

This release adds two ways to see OpenAPI changes outside the terminal. oasdiff git-diff-driver turns git log --patch and git diff into a human-readable changelog, and a new --open flag on changelog and breaking uploads the comparison to oasdiff.com and opens a side-by-side review in your browser. Both work against any spec in any git repo, public or private. Also: a default flip for header comparison, plus a foundation refactor (media-type walker) that shipped behind the scenes.

CLI changes

New subcommands and flags

• New git-diff-driver subcommand (#​954, inspired by Jamie Tanna's post). Wire oasdiff into git as an external diff driver, and git log --patch --ext-diff renders a human-readable OpenAPI changelog inline instead of a raw YAML text diff. Two config lines:

  git config diff.oasdiff.command "oasdiff git-diff-driver"
  echo "openapi.yaml diff=oasdiff" >> .gitattributes
  

  Added (root commit) and removed cases are handled inline; source labels use the short blob hash plus path (e.g. abc1234:openapi.yaml) instead of git's tempfile paths. Full setup in docs/GIT-DIFF-DRIVER.md.
• New --open flag on changelog and breaking (#​955, #​956). After printing the changelog, uploads the comparison to oasdiff.com and opens the rendered side-by-side review in your browser. First run signs in with GitHub (minimal scopes, no repo access) and stores a token locally; subsequent runs skip. The resulting URL is shareable for 7 days, so reviewers can open it without installing the CLI themselves. Filtering and presentation flags (--fail-on, --format, etc.) apply only to terminal output; semantic flags (--flatten-params, --match-inline-refs, etc.) are forwarded to the web review so it matches what you saw locally.

Detection rules

• --case-insensitive-headers now defaults to true (#​939). HTTP header names are case-insensitive per RFC 7230; oasdiff has supported the case-insensitive comparison via flag since v1.x, but the default until now was case-sensitive, so a change between Content-Type and content-type was still flagged as breaking. The default flips to case-insensitive in this release. Pass --case-insensitive-headers=false to opt back into the previous behavior.
• Inline-equivalent and $ref-equivalent subschemas now match (#​938, plus an earlier round in #​930, thanks @​kesha1225). Refactoring an inline schema to a $ref of an equivalent component, or vice versa, no longer produces false "removed subschema" / "added subschema" findings on anyOf / oneOf. The matcher recognizes structurally-equivalent variants regardless of which form they're written in.
• Nullable source-attachment fixed for response-property pairs (#​945). The response-property-became-nullable / -not-nullable changes had asymmetric source-location attachment between matched-pair directions; both sides now attach to the property location consistently.

changelog / breaking output

• Empty-changelog output suggests oasdiff diff (#​946). When oasdiff changelog or breaking finds no significant differences but the underlying diff has document-level changes (info.contact edits, etc.), the CLI hints to try oasdiff diff for the full document-level view. JSON / YAML output also surfaces this via a top-level diff_empty field.

Misc

• ERRORS.md is linked from the validate command's help and error output (#​934).
• Docs reference oasdiff-action v0.0.48 in workflow examples (#​935).

Go package changes

Public validate package

• New github.com/oasdiff/oasdiff/validate package (#​944). The spec-validation logic the validate subcommand uses is now an independent package; library callers can import it directly without going through the CLI. validate.Validate(spec, sourcePath) returns a Findings list (each with a stable rule ID, severity, message, and origin when the loader provides line / column info).

Media-type walker foundation

• New media-type walker reusable across checkers (#​940, with batched checker migrations in #​941, #​942, #​943, #​945, #​947, #​948, #​949, #​951, #​952). Replaces the prior per-checker traversal idioms with a single shared walker over OpenAPI media types and properties. No user-visible behavior change in the common case; the refactor exposed and fixed a handful of latent asymmetries (e.g. the nullable-source attachment in #​945). Callers extending oasdiff with their own checks can now reuse the same walker shape.

Loader: blob-hash git refs

• <ref>:<path> syntax now accepts blob SHAs in addition to commit / tag refs (#​954). Required by git-diff-driver because git's external-diff protocol passes blob hashes, not commit refs. Existing commit / tag / branch ref behavior is unchanged.